Asynchronous Notification

Once a transfer to a bank account is processed, PayBy will send the result to the merchant. The merchant must handle the notification and respond accordingly. The actual time the funds arrive depends on the settlement times of the receiving bank.

Note

1. Duplicate Notifications: The same notification may be sent multiple times. Your system must be able to handle duplicate notifications correctly.

2. Retry Mechanism: If PayBy does not receive a valid or timely response from your system, it will consider the notification failed and retry sending it. PayBy will retry sending the notification up to 7 times at intervals of 2, 10, 10, 60, 120, 360, and 900 minutes, but final delivery success is not guaranteed.

3. Uncertain Order Status: If the order status is unclear or no notification is received, merchants should actively query the transfer status via the API.

4. Signature Verification: Notification requests are signed using PayBy’s RSA private key. Merchants must verify the signature using the PayBy public key, which can be downloaded from the merchant portal. The signing method is the same as for regular API requests.

Request

Http Header

Attributes

• Content-Type String Required

  The media type. Required for operations with a request body. The value is application/<format>, where format is json.

  Example value: application/json

• sign String Required

  When PayBy sends response, PayBy will use its own private key to sign the message, and the merchant uses PayBy 's public key to verify the signature. If the verification is passed, it proves that the response was sent by PayBy and not faked by others.

Http Body

• notify_timestamp Timestamp Required

  The timestamp when PayBy sent the request.

  Example value: 1586849271877

• notify_id String Required

  The unique identification number of this notification within the PayBy system.

  Example value: 202004140007474501

• transferToBankOrder Object

  Attributes

  • requestTime Timestamp Required

    • Time the request was initiated.
    • Example value: 1581493898000

  • merchantOrderNo String Required

    • Unique identifier for the merchant's order.
    • Example value: S10000

  • orderNo String Required

    • Unique identifier for the PayBy transaction.
    • Example value: O1000

  • product String Required

    • Name of the product or service.
    • Example value: Transfer To Bank

  • status String Required

    • Current status of the order.

  • paymentInfo TransferToBankPaymentInfo

    • Detailed information about the payment processing, especially related to fees and timing.

    • Example value:

      {
        "arrivalTime": 1585133416000,
        "payerFeeAmount": {
          "amount": 0,
          "currency": "AED"
        }
      }

    • payerFeeAmount Money

      • The fee charged to the sender (payer), including amount and currency.

    • arrivalTime Timestamp (milliseconds, 3-digit precision)

      • Timestamp when the funds were expected to arrive or did arrive.
      • Example value: 1585133416000

  • amount Money Required

    • Transaction amount.

  • holderName String Required

    • SHA-256 hash of the original name.

  • Iban String Required

    • SHA-256 hash of the original IBAN.

  • swiftCode String

    • SWIFT code of the beneficiary bank.

  • memo String

    • Remarks or notes for the payment.

  • notifyUrl String

    • URL for backend notifications.

  • failDes String

    • Reason for order failure.

  • beneficiaryAddress String

    • SHA-256 hash of the original address.

  • bankReference String

    • Reference number associated with the bank.

  • fundoutAmount Money

    • Amount credited to the beneficiary.

  • rate BigDecimal

    • Exchange rate used for the transaction.

  • networkCode String Required

    • Financial network used.
    • Example value: LOCAL

  • countryCode String

    • Country code of the beneficiary bank.

  • bankName String

    • Name of the beneficiary bank.

  • fedwireCode String

    • Fedwire account code.

  • intermediaryBank String

    • SWIFT code of the intermediary bank.

  • branchName String

    • Name of the bank branch.

  • beneficiaryType String Required

    • Type of beneficiary account.
    • Example value: IBAN

  • purposeCode String

    • Code indicating the purpose of the transaction.
    • Example value: COM

• **notify_time** String

  The parameter is deprecated. Please use the notify_timestamp instead.

• **_input_charset** String

  The parameter is deprecated.

Notification Sample

// Http Header
{
    "Content-Type": "application/json; charset=UTF-8"
}

// Http Body
{
    "_input_charset": "UTF-8",
    "notify_id": "202004140007474501",
    "notify_time": "20200414113800",
    "transferToBankOrder": {
        "amount": {
            "amount": 0.02,
            "currency": "AED"
        },
        "holderName": "00d74f270d2251e8fa6e7f3b1ea06bd3b5f32dfe4719f9df60982c55b24e4898",
        "iban": "1fc44f25c178c422f705054c669cfa6133f6dc8e1fe24b3d96f847667db8b92c",
        "memo": "company single pay",
        "merchantOrderNo": "M188573109026",
        "notifyUrl": "http://www.yoursite.com",
        "orderNo": "911586849271010217",
        "paymentInfo": {
            "arrivalTime": 1586849273000,
            "payerFeeAmount": {
                "amount": 5.0,
                "currency": "D"
            }
        },
        "product": "Transfer To Bank",
        "requestTime": 1586849271877,
        "status": "SUCCESS",
        "swiftCode": "BBME AEAD"
    }
}

Response

Please reply success after receiving the notification, otherwise PayBy will send the notification repeatedly for the same order.

Http Header

• Content-Type String Required

  The media type. Required for operations with a request body. The value is application/<format>, where format is json.

  Example value: application/json

Http Body

• response String Required

  Example value: Success

// Http Header
{
 "Content-Type": "application/json; charset=UTF-8" 
}

// Http Body
{
    "response":"SUCCESS"
}

Response Codes

Code	Message	Description	Workaround
0	SUCCESS	Request was successful	—
400	INVALID_PARAMETER	Invalid request parameters	Adjust request parameters
400	REQUESTTIME_TOO_EARLY	Request time is too far in the past	Adjust request time
400	REQUESTTIME_TOO_LATER	Request time is too far in the future	Adjust request time
402	RATE_LIMIT_REJECT	Too many requests in a short time	Reduce request frequency
403	UNAUTHORIZED	API access not authorized	Contact PayBy
404	SERVICE_NOT_AVAILABLE	API service is currently unavailable	Contact PayBy
500	SYSTEM_ERROR	Internal system error	Contact PayBy and retry later
504	SERVICE_TIMEOUT	Request timed out	Retry later
601	RISK_FAIL	Risk control validation failed	Adjust business logic
62002	ORDER_FAILURE	Attempted to cancel or refund a failed order	Modify merchant order number
62004	MERCHANT_ORDER_NO_NOT_EXIST	Order with the given merchant order number does not exist	Modify merchant order number
62016	MERCHANT_ORDER_NO_EXIST	Duplicate order number with different business parameters	Modify order number
62026	PRODUCT_IS_NOT_APPLIED	Product not applied for	Apply for the product
62028	ORDER_SUCCESS	Order has already been successfully processed	Modify merchant order number
62029	ORDER_CREATED	Order has already been created	Modify merchant order number
62076	FUND_OUT_ABILITY_SUPPORTED	networkCode or fundoutCurrencyCode not enabled or unsupported	Contact PayBy
62101	WRONG_IBAN_FORMAT	Invalid IBAN format	Correct IBAN format
62102	NAME_NOT_FOUND	Name could not be retrieved via IBAN	Correct IBAN
62103	QUERY_API_UNAVAILABLE	Query API is currently unavailable	Retry later
62094	THE_ENTERED_COUNTRY_CODE_IS_INVALID	Invalid country code	Adjust request parameters
62095	THE_ENTERED_CITY_CODE_IS_INVALID	Invalid city code	Adjust request parameters